Dark Engine model importer-exporter

This script enables import and export of Dark Engine static model files (.bin). It reads version 3 (Thief: the Dark Project) and version 4 (Thief 2, System Shock 2) files, and writes version 4 files.

Installation

Get the io_scene_dark_bin-*.*.*.zip file from the Files section.

Install this script as an add-on:

1. Open Blender's User Preferences window and go to the Addons tab.
2. Click Install from File and specify the downloaded io_scene_dark_bin-*.*.*.zip file or the unpacked io_scene_dark_bin.py file.
3. Enable the Import-Export: Dark Engine Static Model addon.
4. To make your changes persistent, click Save User Settings.

Assigning textures

In Dark Engine models, texture files are referenced by object faces. To put a texture on a face, assign it a material with the same name as the texture file (for example, blood.pcx). Note that any textures associated with the material do not affect the exported texture name.

If a mesh has no material in Blender, the addon will mindlessly assign material index 0 to all its faces. If a mesh doesn't have a UV map, all its UV coordinates will be set to zeroes. Don't forget to set up your materials and create your UV maps in advance.

Making sharp creases

The addon supports export of sharp edges; import of such edges is not supported at this time.

To set up sharp edges for export, use the Edge Split modifier and adjust its options as needed. If a mesh doesn't have this modifier, all exported edges will be smooth.

Notes:

• To make the Blender viewport show the result you are going to get, use the Set Smooth command on the mesh object.
• Make sure the modifier is enabled (its eye icon is on) during export.

Translucency and emission

To specify translucency and emission for a material (that is, make it see-through or bright), use the Translucency and Emit options in the Shading group of material options. If you specify an Emit value higher than 1.0, it will be clamped at 1.0 in the exported file. During import, the same options are set automatically for loaded materials.

You can disable export of translucency or emission data by clearing the Use Translucency and Use Emission options in the file save dialog. They are selected by default.

How the format's features are handled

In addition to geometry and hierarchy, the Dark Engine model format supports some fairly sophisticated features. Blender has matching features for some of them.

Bounding Boxes

In Dark Engine models, the bounding box does not necessarily tightly fit the model geometry. It can be useful to view and especially set the bounding box, particularly when you make custom modifications to existing models.

During import, the bounding box is loaded as a mesh object with only two vertices and an edge between them. The object has the base name "bbox", and its display type is set to Bounds.

During export, if there is a mesh whose name starts with "bbox" (the case doesn't matter), that mesh's bounding box will be used. Otherwise, the bounding box values will be calculated based on the exportable geometry.

Note: Don't rotate your custom bounding box object; this will distort the dimensions.

Model Origin

During export, you can set the location of the model's origin. To keep the same offset as in the Blender scene, make sure the Model origin is at world origin export option is selected. If you clear this option, the model origin ends up at the centre of the model geometry (vertices are considered only if they are associated with faces).

Attachments

Models can have attachment points (hotspots) for external objects. To define a hotspot for an object, create an empty and make it a child of the object. During export, empties are sorted by name per parent object. Keep this in mind when you give them names, so that you get the correct hotspot order in DromEd.

Subobject Motion

In Dark Engine models, there are two kinds of subobject motion: rotation (like a wheel on an axle) and sliding (like a piston). A subobject can either rotate or slide, but not both at once. The range of motion is hard-coded in the model file. To enable rotation or sliding for a subobject:

1. Make sure the subobject has a parent.
2. The X axis is used as the motion axis. Make sure the subobject is oriented accordingly.
3. Add a Limit Rotation (for a rotating subobject) or Limit Location (for a sliding subobject) constraint to the subobject.
4. Set the range of motion by specifying the minimum and maximum values for the X axis.

• You don't have to enable the check boxes that put the limits in effect, you just need to specify the values. Note that Blender's Local Space option for the rotation and location limits is a bit of a misnomer: it really means parent space. Therefore, you might not be able to test your settings in a WYSIWYG fashion. Export is not affected by any constraint settings other than the limit values.
• If you specify both a Limit Rotation and a Limit Location constraint, then the Limit Location constraint is applied (the subobject slides).
• If an object has a parent but no constraints, it will be exported as a rotating subobject with a zero rotation range.
• During import, the constraints are added automatically.

Dealing with transparency

In the Dark Engine, how correctly transparent surfaces are rendered depends on the order that polygons are listed in the model file. The Polygon sorting method export option helps you change the look of your transparent models.

BSP
This choice slices and orders polygons using a BSP tree algorithm. However, this early implementation produces acceptable results only on simple geometry. Note that using this feature can increase the polygon count unpredictably, easily exceeding the format's limits.

By vertex group
This choice helps you control the ordering of polygons through the use of named vertex groups. The technique isn’t a one-size-fits-all solution, but it leaves the poly count unchanged. Considering the kind of engine you're dealing with, you’d be hard pressed to find a situation where the method would be useless.
Vertex group naming is the one thing you need to be careful with; it may involve some trial and error.
Here’s an example to put things in perspective. Suppose you have a wine glass in your mission. For the glass to look properly transparent, its polygons must be rendered from back to front. You use vertex groups to batch your polygons for rendering, in alphabetical order.
Here’s how you can arrange the polygon batches in the glass:

The numbers mark the drawing order. Now, for each of the batches:

1. Create a vertex group.
2. Deselect everything and select the polygons you need.
3. Assign your selection to the vertex group.

Example:

If you can remember ZX Spectrum Basic, the sparse numbering technique from that era may come in handy here.
Here’s what you get with that kind of grouping:

Admittedly, the glass will still have some problems if you look from below, but you’re unlikely to do that kind of crawling in-game.

Notes:

• Strictly speaking, it’s vertices not polygons that are added to groups. The exporter considers a polygon “in” a group if all of its vertices are in it. If a polygon finds its way into multiple groups, only the first one alphabetically is used.
• Polygons that aren’t associated with any groups are drawn last.
• In objects that are lumped together during export, vertex group membership is merged, including identically-named vertex groups.